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There are tons and then some useful guides on how to keep your forks updated against the 
upstream repositories (and if you’re wondering why you would want to use forks in an enterprise 
setting, check out a few reasons here). In this blog I will introduce you to few aspects of how 
forking interacts with upstream: the basics, the gotcha’s, and an cool tip. To top it off I will then 
make you very jealous, or very eager, the choice is yours. Interested? Read on. 

The base workflow to keep up-to-date and contribute 

Let me start by detailing a common setup and the most basic workflow to interact with upstream 
repositories. 

In a standard setup you generally have an origin and an upstream remote - the latter being the 
gatekeeper of the project or the source of truth to which you wish to contribute to. 

First, verify that you have already setup a remote for the upstream repository - and hopefully an 
origin too: 


lgit remote -v 
2 

3origin git@bitbucket.org:my-user/some-project.git (fetch) 
4origin git@bitbucket.org:my-user/some-project.git (push) 


If you don’t have an upstream you can add it simply with the remote command: 
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lgit remote add upstream git@bitbucket.org: some-gatekeeper-maintainer/some-project . git 


Verify that the remote is added correctly: 

lgit remote -v 
2 

3origin git@bitbucket.org:my-user/some-project.git (fetch) 
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4origin git@bitbucket.org:my-user/some-project.git (push) 

5upst ream git@bitbucket . org : some-gatekeeper-maintainer/some-proj ect .git ( fetch) 

6upst ream git@b it bucket . org : some-gatekeeper-maintainer/some-proj ect .git ( push ) 


Now you can collect the latest changes of the upstream repository with fetch (repeat this every 
time you want to get updates): 


lgit fetch upstream 
2 

3 ( If the project has tags that have not merged to master you should also do: git fetch 
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Generally you want to keep your local master branch as a close mirror of the upstream master 
and execute any work in feature branches (that might become pull requests later). 

At this point it does not matter if you use merge or rebase, the result will typically be the same. 
Let’s use merge: 


lgit checkout master 
2git merge upstream/master 


When you want to share some work with the upstream maintainers you branch off master, 
create a feature branch and when you’re satisfied you push it to your remote repository. 

You can also use rebase instead then merge to make sure the upstream has a clean set of 
commits (ideally one) to evaluate: 


lgit checkout -b feature-x 
2 

3#some work and some commits happen 
4#some time passes 
5 

6git fetch upstream 

7git rebase upstream/master 


If you need to squash a few commits into one you can use the awesome rebase interactive at 
this point. 

After the above, publish your work in your remote fork with a simple push: 


lgit push origin feature-x 


A slight problem rises if you have to update your remote branch feature-x after you published 
it, because of some feedback from the upstream maintainers. You have a few options: 

• Create a new branch altogether with the updates from you and the upstream. 

• merge the updates from upstream in your local branch which will record a merge commit. This 
will clutter the upstream repository. 

• Rebase your local branch on top of the updates from upstream and do a force push onto your 
remote branch: 

lgit push -f origin feature-x 


Personally I prefer to keep the history as clean as possible and go for option three, but different 
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teams have different work flows. OBVIOUS ALERT!! You should do this only when working with 
your own fork. Rewriting history of shared repositories and branches is something you 
should NEVER do. 

Tip of the day: Ahead/Behind numbers in the prompt 

After a fetch, git status shows you how many commits you are ahead or behind of the remote 
the branch it syncs to. Wouldn’t it be nice if you could see this information at your faithful 
command prompt? I thought so too so I started tapping with my bash chopsticks and cooked it 
up. 

Here is how it will look on your prompt once you configure it: 


lnick-macbook-air:~/dev/projects/stash [1 | 94] $ 


And this is what you need to add to your .bashrc or equivalent, just a single function: 


lfunction ahead_behind { 

2 curr_branch=$(git rev-parse — abbrev-ref HEAD); 

3 curr_remote=$(git config branch. $curr_branch. remote) ; 

4 curr_merge_branch=$(git config branch. $curr_branch. merge | cut -d / -f 3); 

5 git rev-list — left-right — count $curr_branch. . . $curr_remote/$curr_merge_b ranch 
6 } 


You can enrich your bash prompt with this new function ahead_behind to have the desired 
effect. I leave the colorization as an exercise for the reader (not to clutter the tip too much). 

Sample prompt: 


lexport PSl="\h:\w[\$(ahead_behind) ] $" 


Inner workings 

For those who like details and explanations here is how it works: 

We get the symbolic name for the current HEAD i.e. the current branch: 

lcurr_branch=$(git rev-parse — abbrev-ref HEAD); 

We get the remote that the current branch is pointing to: 

lcurr_remote=$(git config branch. $curr_branch. remote) ; 

We get the branch onto which this remote should be merged to (with a cheap Unix trick to 
discard everything up to and including the last forward slash /): 

lcurr_merge_branch=$(git config branch. $curr_branch. merge | cut -d / -f 3); 


Now we have what we need to collect the counts for the commits we are ahead or behind: 


lgit rev-list — left-right — count $curr_branch. . . $curr_remote/$curr_merge_branch | tr 
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We use the age old Unix tr to convert the TAB to a separator | . 


Conclusions 

I hope this basic walk-through on upstream is useful for those unfamiliar with the process. Also 
note that the latest uber-fresh Stash release includes fork synchronization which basically 
relieves the developer from all the burden of keeping up to date with its forks, check it out! 

Follow me @durdn and the awesome @AtlDevtools team for more DVCS rocking. 
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Comments (5) 



Nice post, particularly for the ‘ahead_behind()’ function. 

Just wanted to ask if you were aware of the @{upstream} ref short-hand, as it seems like 
it would simplify some of the above: e.g. ‘git rev-parse -abbrev-ref @{upstream}’ instead 
of mixing the output of one git-config call into another, and I haven’t tested it but 
‘@{upstream}’ by itself should be able to replace ‘$curr_remote’ in the examples above. 


By Eric James Michael Ritz on July 22, 2013 / Reply 



Hey Eric, thanks for the note! Indeed @{upstream} looks exactly what’s 
needed there. 

By Nicola Paolucci on July 23, 2013 


Pingback: Gaining Fluency With Git Commands I Terri's Tech Adventures 



Nice post. You should definitely check out https://github.com/rfnash/liquidprompt if you 
are keen into your prompt showing you relevant information about your git repository. 

By Mujtaba Hussain on July 23, 2013 / Reply 



Hey Mujtaba, liquidprompt is awesome and I have already been using it for a 
while. Great recommendation. 

By Nicola Paolucci on July 24, 2013 
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